################## Настройка сервисов ################## .. contents:: :depth: 4 Файлы сервисов PromUC располагаются в отдельных каталогах пути установки, по умолчанию ``/opt/promuc``, а также в каталоге хранения томов Docker, по умолчанию ``/var/lib/docker/volumes``. Основные файлы ``framework``: .. list-table:: :header-rows: 1 * - Путь - Назначение * - conf - Каталог с конфигурационными файлами * - docker-compose-cert.yml - Шаблон конфигурации Docker Compose, используемый при генерации сертификатов или использовании имеющихся * - docker-compose-le.yml - Шаблон конфигурации Docker Compose, используемый при генерации сертификатов посредством сервиса Let's Encrypt * - install.sh - Скрипт установки * - template.env - Шаблон файла .env ************ Timescale DB ************ Конфигурационные файлы ====================== В каталоге ``postgres/conf`` располагаются файлы инициализации баз данных: .. list-table:: * - 200_disable_telemetry.sql - Отключает телеметрию * - 201_framework-init.sql - Инициализация БД ``framework`` * - 201_gitea-init.sql - Инициализация БД ``gitea`` * - 202_metrics-init.sql - Инициализация БД ``metrics`` Файл .env ========= В файле-шаблоне ``template.env`` указаны переменные, значения которых будут использованы для создания соответствующих файлов docker-секретов в папке ``.secrets``. В файл .env они не переносятся при установке сервиса. .. list-table:: * - | FRAMEWORK_DB | FRAMEWORK_DB_USER | FRAMEWORK_DB_PASS - | ``postgres/.secrets/framework-db`` | ``postgres/.secrets/framework-db-user`` | ``postgres/.secrets/framework-db-pass`` * - | GITEA_DB | GITEA_DB_USER | GITEA_DB_PASS - | ``postgres/.secrets/gitea-db`` | ``postgres/.secrets/gitea-db-user`` | ``postgres/.secrets/gitea-db-pass`` * - | METRICS_DB | METRICS_DB_USER | METRICS_DB_PASS - | ``postgres/.secrets/metrics-db`` | ``postgres/.secrets/metrics-db-user`` | ``postgres/.secrets/metrics-db-pass`` * - | POSTGRES_PASSWORD - | ``postgres/.secrets/postgres-passwd`` Публикация доступа к Timescale DB ================================= В случае если требуется предоставить сторонний доступ к контейнеру ``postgres`` необходимо: 1. в файле ``postgres/docker-compose.yml`` снять комментирование строк: .. code-block:: ## внешнее подключение к postgres # extends: # service: postgres # file: ./extends.docker-compose.yml 2. в файле ``proxy/conf/traefik.yml`` снять комментирование строк: .. code-block:: ## внешнее подключение к postgres # postgres: # address: :5432 3. в файле ``proxy/docker-compose.yml`` снять комментирование строк: .. code-block:: ## внешнее подключение к postgres # - 5432:5432 4. выполнить рестарт сервисов: .. code-block:: # docker compose up -d --force-recreate proxy postgres **************** PromUC FrameWork **************** Файл config_postgres.json ========================= Конфигурационный файл-шаблон ``framework/conf/template.config_postgres.json`` хранит настройки подключения к БД: .. code-block:: json { "host": "172.16.16.254", "port": "5432", "dbname": "", "user": "", "password": "" } При установке FrameWork значения параметров ``dbname``, ``user``, ``password`` заполняются из файлов: .. list-table:: * - dbname - postgres/.secrets/framework-db * - user - postgres/.secrets/framework-db-user * - password - postgres/.secrets/framework-db-pass Настройки процесса fcgi ======================= Для индивидуальной настройки параметров контейнера FrameWork необходимо получить из него файл конфигурации ``lighttpd.conf``: .. code-block::console cd /opt/promuc/framework/conf docker compose cp framework:/app/lighttpd.conf . chown 33 lighttpd.conf Полученный файл необходимо добавить в качестве тома в конфигурацию Docker Compose: docker-compose.yml: .. code-block:: services: framework: ... volumes: ... - ./conf/lighttpd.conf:/app/lighttpd.conf:ro lighttpd.conf: .. code-block:: server.modules = ( "mod_fastcgi", ) fastcgi.debug = 0 fastcgi.server = ( "/" => (( "bin-path" => "/var/www/html/api/index.fcgi", "socket" => "/tmp/app.sock", "check-local" => "disable", "max-procs" => 1, "write-timeout" => 15, "read-timeout" => 15, )) ) server.username = "www-data" server.groupname = "www-data" server.port = 80 server.document-root = "/var/www/html" server.compat-module-load = "disable" server.http-parseopt-host-strict = "disable" server.http-parseopts = ( "url-normalize" => "disable", ) Дополнительные настройки процесса FrameWork ------------------------------------------- Параметры настройки fcgi-процесса FrameWork содержатся в секции ``fastcgi.server``. ``"max-procs" => 1`` - не рекомендуется устанавливать значения более 1, т.к. FrameWork не поддерживает в текущей версии более 1-го процесса. ``"write-timeout" => 15`` - количество секунд до прерывания при попытке записи на сервер FCGI (по умолчанию: 0; тайм-аут отсутствует). Оптимальная величина подбирается на основании обрабатываемой FrameWork нагрузки. ``"read-timeout" => 15`` - количество секунд до прерывания при попытке чтения из сервера FCGI (по умолчанию: 0; тайм-аут отсутствует). Оптимальная величина подбирается на основании обрабатываемой FrameWork нагрузки. ``"connect-timeout"`` - количество секунд до прерывания подключения к серверу FCGI (по умолчанию: 8). Рекомендуется увеличивать если старт FrameWork длится более 8 с. Документация https://redmine.lighttpd.net/projects/lighttpd/wiki/Mod_fastcgi Дополнительные настройки сервера lighttpd ----------------------------------------- ``"server.listen-backlog"`` - размер очереди соединений (по умолчанию: 1024). ``"server.max-connections"`` - максимальное количество соединений (по умолчанию: 1024). Устанавливается не более трети или половины от значения ``"server.max-fds"``. ``"server.max-fds"`` - максимальное количество файловых дескрипторов (по умолчанию равен значению ``ulimit -n``). Документация https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_ConfigurationOptions *************** Настройка Gitea *************** Файл .env ========= .. code-block::shell SERVICE_DOMAIN=dev.4iot.pro GITEA_IMG=psm/gitea GITEA_TAG=latest RUNNER_TAG=0.2.6 GITEA_ORG=promuc FLUENTBIT_ADDR=fluentbit GITEA_ENABLE_ACTIONS=off | ``GITEA_IMG`` - используемый docker-образ Gitea | ``GITEA_TAG`` - тег используемого docker-образа | ``RUNNER_TAG`` - тег используемого docker-образа Act Runner | ``GITEA_ORG`` - название организации создаваемой в Gitea | ``FLUENTBIT_ADDR`` - адрес сервера fluentbit | ``GITEA_ENABLE_ACTIONS`` - включает или отключает использование сервиса Gitea Act runner и Gitea GITEA_ENABLE_ACTIONS Настройка контейнер-плагинов ============================ PromUC позволяет запускать дополнительный функционал в отдельных контейнер-плагинах с исполнением пользовательского кода. При установке в Gitea загружаются репозитории шаблоны с примерами пользовательского кода на Python, Go, FastCGI. Список репозиториев указан в файле ``repos.yml``. Для управления запуском и остановки контейнеров используется сервис Updater, при установке которого функционируется Systemd-сервис ``promuc-updater.service``. Данный сервис принимает webhook от Gitea об изменениях в репозиториях плагинов и запускает или останавливает контейнеры. Для создания плагина необходимо создать новый репозиторий на основе соответствующего щаблона и выполнить соотвествующие настройки. Дополнительный модуль с Python-приложением ------------------------------------------ Реализация дополнительного модуля (plugin) PromUC в виде docker-контейнера и Python web-приложения. После запуска данного модуля возможно обращение к приложению посредством отправки запросов по адресу ``http://plugin_ИмяОрганизации_ИмяРепозитория`` или с указанием TCP-порта ``http://plugin_ИмяОрганизации_ИмяРепозитория:Порт``. Например: .. code-block::shell $ curl -v http://plugin_promuc_example_python * Trying 172.16.16.14:80... * Connected to plugin_promuc_example_python (172.16.16.14) port 80 (#0) > GET / HTTP/1.1 > Host: plugin_promuc_example_python > User-Agent: curl/7.74.0 > Accept: */* > * Mark bundle as not supporting multiuse < HTTP/1.1 200 OK < Server: Werkzeug/2.3.6 Python/3.11.4 < Date: Sun, 16 Jul 2023 07:02:48 GMT < Content-Type: text/html; charset=utf-8 < Content-Length: 26 < Connection: close < * Closing connection 0 Hello from python-http-cgi Настройка модуля ^^^^^^^^^^^^^^^^ Код приложения помещается в папку ``src``. Изменение функционала контейнера, например, добавление дополнительных библиотек, настройка сборки приложения и прочее выолняется конфигурирование файла ``Dockerfile``. Контейнер плагина запускается в сети PromUC c параметрами: * без публикации сетевых портов на хосте * ``--network proxy_backend`` - в сети PromUC * ``--user 1`` - выполнением процессов с правами ограниченного пользователя * ``--restart=on-failure:2`` - рестарт после ошибки ограниченное число раз Параметры дополнительного модуля задаются в файле ``plugin.yml``. Запуск модуля ^^^^^^^^^^^^^ Для запуска дополнительного модуля необходимо указать ``run: true`` в ``plugin.yml``. Соответственно, для остановки указать ``run:false``. При старте модуля производится сборка docker-образа, поэтому первичный запуск или после внесения изменений в содержимое репозитория модуля выполняется с задержкой, длина которой зависит от сложности сборки приложения модуля, производительности хоста PromUC и его текущей нагрузки. После управляемой остановки модуля его контейнер удаляется, при аварийной остаётся выключенным. Информация о запущенном контейнере добавляется в файл ``install/config.json``, при остановке удаляеется. Управление модулем из операционной системы хоста PromUC ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Остановка дополнительного модуля: .. code-block::shell > docker stop plugin_promuc_example_python Старт дополнительного модуля: .. code-block::shell > /opt/promuc/updater/host/start_plugins.sh plugin_promuc_example_python success start plugin_promuc_example_python Если модуль ранее не запускался, отсутствует docker-образ модуля, то команды выполнится с ошибкой и модуль не будет запущен. При рестарте операционной системы хоста служба promuc-updater выполняет старт дополнительных модулей указанных в файле `install/config.json` Контроль работы модуля ^^^^^^^^^^^^^^^^^^^^^^ * С помощью docker-cli: .. code-block::shell > docker ps -f name=plugin_promuc_example_python CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 2ca60195c879 plugin_promuc_example_python "/app/app" 22 seconds ago Up 21 seconds 80/tcp plugin_promuc_example_python * С помощью Portainer, в разделе Containers. Состав дополнительного модуля ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * docker-контейнер на базе ``python:slim`` * приложение ``app`` Файл конфигурации ^^^^^^^^^^^^^^^^^ plugin.yml: * ``type:container`` - обозначает тип дополнительного модуля * ``port:`` - номер TCP-порта веб-сервера * ``forks:`` - количество запускаемых форков приложения * ``run:`` - признак запуска дополнительного модуля Дополнительный модуль с Go-приложением -------------------------------------- Реализация дополнительного модуля (plugin) PromUC в виде docker-контейнера и Go web-приложения. После запуска данного модуля возможно обращение к приложению посредством отправки запросов по адресу ``http://plugin_ИмяОрганизации_ИмяРепозитория`` или с указанием TCP-порта ``http://plugin_ИмяОрганизации_ИмяРепозитория:Порт``. Например: .. code-block::shell $ curl -v http://plugin_promuc_example_go -d "test" * Trying 172.16.16.38:80... * Connected to plugin_promuc_example_go (172.16.16.38) port 80 (#0) > POST / HTTP/1.1 > Host: plugin_promuc_example_go > User-Agent: curl/7.74.0 > Accept: */* > Content-Length: 4 > Content-Type: application/x-www-form-urlencoded > * upload completely sent off: 4 out of 4 bytes * Mark bundle as not supporting multiuse < HTTP/1.1 200 OK < Content-type: text/plain < Content-Length: 2 < Date: Thu, 06 Jul 2023 14:28:55 GMT < Server: lighttpd/1.4.69 < * Connection #0 to host plugin_promuc_example_go left intact Настройка модуля ^^^^^^^^^^^^^^^^ Код приложения помещается в папку ``src``. Изменение функционала контейнера, например, добавление дополнительных библиотек, настройка сборки приложения и прочее выолняется конфигурирование файла ``Dockerfile``. Контейнер плагина запускается в сети PromUC c параметрами: * без публикации сетевых портов на хосте * ``--network proxy_backend`` - в сети PromUC * ``--user 1`` - выполнением процессов с правами ограниченного пользователя * ``--restart=on-failure:2`` - рестарт после ошибки ограниченное число раз Параметры дополнительного модуля задаются в файле ``plugin.yml``. Запуск модуля ^^^^^^^^^^^^^ Для запуска дополнительного модуля необходимо указать ``run: true`` в ``plugin.yml``. Соответственно, для остановки указать ``run:false``. При старте модуля производится сборка docker-образа, поэтому первичный запуск или после внесения изменений в содержимое репозитория модуля выполняется с задержкой, длина которой зависит от сложности сборки приложения модуля, производительности хоста PromUC и его текущей нагрузки. После управляемой остановки модуля его контейнер удаляется, при аварийной остаётся выключенным. Информация о запущенном контейнере добавляется в файл ``install/config.json``, при остановке удаляеется. Управление модулем из операционной системы хоста PromUC ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Остановка дополнительного модуля: .. code-block::shell > docker stop plugin_promuc_example_go plugin_promuc_example_go Старт дополнительного модуля: .. code-block::shell > /opt/promuc/updater/host/start_plugins.sh plugin_promuc_example_go success start plugin_promuc_example_go Если модуль ранее не запускался, отсутствует docker-образ модуля, то команды выполнится с ошибкой и модуль не будет запущен. При рестарте операционной системы хоста служба promuc-updater выполняет старт дополнительных модулей указанных в файле ``install/config.json`` Контроль работы модуля ^^^^^^^^^^^^^^^^^^^^^^ * С помощью docker-cli: .. code-block::shell > docker ps -f name=plugin_promuc_example_go CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 2ca60195c879 plugin_promuc_example_go "/app/app" 22 seconds ago Up 21 seconds 80/tcp plugin_promuc_example_go * С помощью Portainer, в разделе Containers. Состав дополнительного модуля ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - docker-контейнер на базе ``debian:stable-slim`` - приложение ``app`` - файл plugin.yml Файл конфигурации ^^^^^^^^^^^^^^^^^ plugin.yml: - ``type:container`` - обозначает тип дополнительного модуля - ``port:`` - номер TCP-порта веб-сервера - ``forks:`` - количество запускаемых форков приложения - ``run:`` - признак запуска дополнительного модуля Дополнительный модуль с FastCGI-приложением ------------------------------------------- Реализация дополнительного модуля (plugin) PromUC в виде docker-контейнера и FastCGI web-приложения. После запуска данного модуля возможно обращение к приложению посредством отправки запросов по адресу ``http://plugin_ИмяОрганизации_ИмяРепозитория`` или с указанием TCP-порта ``http://plugin_ИмяОрганизации_ИмяРепозитория:Порт``. Например: .. code-block::shell $ curl -v http://plugin_promuc_fcgi_example1 -d "test" * Trying 172.16.16.38:80... * Connected to plugin_promuc_fcgi_example1 (172.16.16.38) port 80 (#0) > POST / HTTP/1.1 > Host: plugin_promuc_fcgi_example1 > User-Agent: curl/7.74.0 > Accept: */* > Content-Length: 4 > Content-Type: application/x-www-form-urlencoded > * upload completely sent off: 4 out of 4 bytes * Mark bundle as not supporting multiuse < HTTP/1.1 200 OK < Content-type: text/plain < Content-Length: 2 < Date: Thu, 06 Jul 2023 14:28:55 GMT < Server: lighttpd/1.4.69 < * Connection #0 to host plugin_promuc_fcgi_example1 left intact Настройка модуля ^^^^^^^^^^^^^^^^ Код приложения помещается в папку ``src``. Изменение функционала контейнера, например, добавление дополнительных библиотек, настройка сборки приложения и прочее выолняется конфигурирование файла ``Dockerfile``. Контейнер плагина запускается в сети PromUC c параметрами: * без публикации сетевых портов на хосте * ``--network proxy_backend`` - в сети PromUC * ``--user 1`` - выполнением процессов с правами ограниченного пользователя * ``--restart=on-failure:2`` - рестарт после ошибки ограниченное число раз Параметры дополнительного модуля задаются в файле ``plugin.yml``. Запуск модуля ^^^^^^^^^^^^^ Для запуска дополнительного модуля необходимо указать ``run: true`` в ``plugin.yml``. Соответственно, для остановки указать ``run:false``. При старте модуля производится сборка docker-образа, поэтому первичный запуск или после внесения изменений в содержимое репозитория модуля выполняется с задержкой, длина которой зависит от сложности сборки приложения модуля, производительности хоста PromUC и его текущей нагрузки. После управляемой остановки модуля его контейнер удаляется, при аварийной остаётся выключенным. Информация о запущенном контейнере добавляется в файл ``install/config.json``, при остановке удаляеется. Управление модулем из операционной системы хоста PromUC ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Остановка дополнительного модуля: .. code-block::shell > docker stop plugin_promuc_example_fcgi plugin_promuc_example_fcgi Старт дополнительного модуля: .. code-block::shell > /opt/promuc/updater/host/start_plugins.sh plugin_promuc_example_fcgi success start plugin_promuc_example_fcgi Если модуль ранее не запускался, отсутствует docker-образ модуля, то команды выполнится с ошибкой и модуль не будет запущен. При рестарте операционной системы хоста служба promuc-updater выполняет старт дополнительных модулей указанных в файле ``install/config.json``. Контроль работы модуля ^^^^^^^^^^^^^^^^^^^^^^ * С помощью docker-cli: .. code-block::shell > docker ps -f name=plugin_promuc_example_fcgi CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 2ca60195c879 plugin_promuc_example_fcgi "/app/app" 22 seconds ago Up 21 seconds 80/tcp plugin_promuc_example_fcgi * С помощью Portainer, в разделе Containers. Состав модуля ^^^^^^^^^^^^^ - docker-контейнер на базе ``debian:stable-slim`` - web-сервер ``lighttpd`` с включённым модулем ``mod_fastcgi`` - приложение ``app`` использующее для взимодействия с web-сервером протокол FastCGI Файл конфигурации plugin.yml ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ plugin.yml: - ``type:container`` - обозначает тип дополнительного модуля - ``port:`` - номер TCP-порта веб-сервера - ``forks:`` - количество запускаемых форков приложения - ``run:`` - признак запуска дополнительного модуля ***************** PromUC RuleEngine ***************** Данный сервис включает в себя выполнение контейнеров: ``ruleengine``, ``ruleengine-front``, ``ruleengine-transport``, ``ruleengine-cov``. Дополнительно для управления данными используется сервис ``redis``. Для взаимодействия с другими компонентами и потребителями в сети заказчика используются сетевые tcp-порты: ``5555``, ``5554``, ``7777``. Конфигурация PromUC RuleEngine хранится в репозитории, название которого и адрес определяются посредством переменных в файле ``.env``: .. code-block:: shell RULEENGINE_REPO=ruleengine-config RULEENGINE_REPO_URL=https://${SERVICE_DOMAIN:-localhost}/promuc/ruleengine-config.git Сервис использует локальную копию репозитория в docker-томе ``promuc_storage``, которую синхронизирует с центральным репозиторием в Gitea посредством сервиса ``Updater``. ******* Updater ******* Данный сервис используется для синхронизации репозитория с конфигурацией PromUC RuleEngine и управления контейнерами плагинов. При установке настраивается сервис systemd ``promuc-updater.service``, который в обрабатывает поступающие HTTP POST запросы и выполняет необходимые команды по синхронизации и пуск/остановку контейнеров плагинов. Проверить состояние сервиса: .. code-block:: shell $ systemctl status promuc-updater.service ● promuc-updater.service - PromUC local Updater service Loaded: loaded (/usr/local/lib/systemd/system/promuc-updater.service; enabled; preset: enabled) Active: active (running) since Mon 2024-12-16 20:43:55 MSK; 1 day 16h ago Docs: https://promuc.ru/#doc Process: 628487 ExecStartPost=/opt/promuc/updater/host/start_plugins.sh (code=exited, status=0/SUCCESS) Main PID: 628485 (webhook) Tasks: 8 (limit: 4644) Memory: 11.1M CPU: 586ms CGroup: /system.slice/promuc-updater.service └─628485 /opt/promuc/updater/webhook -hotreload -hooks /opt/promuc/updater/host/hooks.yaml -verbose -ip 192.168.0.2 -port 9090 Dec 17 12:32:51 vpn1 webhook[628485]: [webhook] 2024/11/17 12:32:51 [983bdc] 200 | 2 B | 13.893µs | | OPTIONS / Dec 17 12:33:24 vpn1 webhook[628485]: [webhook] 2024/11/17 12:33:24 [2b7599] 200 | 2 B | 36.584µs | www | GET / Dec 17 17:44:55 vpn1 webhook[628485]: [webhook] 2024/11/17 17:44:55 [4566fd] 200 | 2 B | 74.42µs | 185.90.50.107:9090 | GET / | Выполнить рестарт сервиса командой ``systemctl restart promuc-updater.service``. | Остановить сервис ``systemctl stop promuc-updater.service``. | Запустить сервис ``systemctl start promuc-updater.service``.